home *** CD-ROM | disk | FTP | other *** search
/ Web Page Construction Kit 3.0 / Web Page Construction Kit 3.0.iso / pc / source / 3rdparty / cgi / libs / libwww / install.txt < prev    next >
Encoding:
Text File  |  1995-12-07  |  11.8 KB  |  251 lines
  1. libwww-perl Installation Information
  2. ====================================
  3. # $Id: INSTALL.txt,v 0.15 1994/09/21 01:23:18 fielding Exp $
  4.  
  5. See the files README.html and Artistic.txt for licensing and distribution info.
  6. See the file LWP_Changes.pl for a complete list of changes and version history.
  7.  
  8. The latest version of libwww-perl can always be found at:
  9.  
  10.        http://www.ics.uci.edu/WebSoft/libwww-perl/
  11.  
  12. or by anonymous ftp from
  13.  
  14.        ftp://liege.ics.uci.edu/pub/arcadia/libwww-perl/
  15.  
  16.  
  17. ==========================================================================
  18. Installation instructions:
  19.  
  20. 1. Get the libwww-perl package from the distribution site (above).  Normally,
  21.    it will be in the form of a compressed unix tar file.  If it has not
  22.    already been decompressed by your WWW client, then do one of:
  23.  
  24.        % uncompress libwww-perl-V.vv.tar.Z
  25.        % gunzip libwww-perl-V.vv.tar.gz
  26.  
  27.    depending on which compressed version you downloaded. "V.vv" should
  28.    be replaced with the library version number, e.g. "0.40".
  29.  
  30.  
  31. 2. Move the resulting libwww-perl-V.vv.tar file to the directory above
  32.    where you want to install libwww-perl, cd to that directory, and do
  33.  
  34.        % tar xvf libwww-perl-V.vv.tar
  35.  
  36.    to create the directory ./libwww-perl-V.vv containing the following:
  37.  
  38.        Artistic.txt   -- the Artistic License governing redistribution
  39.                          of the libwww-perl package.
  40.        INSTALL.txt    -- this file
  41.        LWP_Changes.pl -- the list of known problems and version information.
  42.        Makefile       -- a Makefile for automating the initial configuration.
  43.        RCS/           -- the complete RCS repository, including all versions.
  44.        README.html    -- primary source of information about libwww-perl
  45.        get            -- a simple program for performing WWW GET requests from
  46.                          the command-line. The name of the program determines
  47.                          what request method to be used (i.e. create a link to
  48.                          it called "head" and you have a program that does
  49.                          HEAD requests). This program demonstrates the power
  50.                          and simplicity of the libwww-perl interface. 
  51.        hostname.pl    -- a library for determining the fully qualified domain
  52.                          name for the host running libwww-perl.
  53.        mime.types     -- the standard MIME content-types and default filename
  54.                          extensions in the same format as that used by NCSA
  55.                          httpd_1.3 and many WWW clients. 
  56.        sys_socket_ph.c - A simple C program for displaying your system's
  57.                          symbolic values normally found in sys/socket.ph.
  58.        testbot        -- a simple program for testing the wwwbot.pl package. 
  59.        testdates      -- a simple program for testing the wwwdates.pl package. 
  60.        testescapes    -- a program for testing wwwurl'escape and unescape.
  61.        testlinks      -- a simple program for testing HTML link extraction and
  62.                          combinations of GET and HEAD requests.
  63.        www.pl         -- the primary entry point for WWW requests -- give it
  64.                          any absolute URL and a request method and it will
  65.                          try to perform the method using the URL's protocol
  66.                          scheme (or a proxy). 
  67.        wwwbot.pl      -- a package for implementing the robot exclusion
  68.                          protocol.
  69.        wwwdates.pl    -- a package of library utilities for reading,
  70.                          manipulating, and writing dates as they are formatted
  71.                          by most World-Wide Web software and protocols. 
  72.        wwwerror.pl    -- a package for defining and generating error messages
  73.                          for requests which did not make it outside the client
  74.                          program. 
  75.        wwwfile.pl     -- a package for performing local file requests (URLs of
  76.                          the form file://localhost/*) and returning a response
  77.                          as if it came from an HTTP server. 
  78.        wwwhtml.pl     -- a package of library utilities for reading and
  79.                          manipulating HTML documents. 
  80.        wwwhttp.pl     -- a package for performing HTTP requests (URLs of the
  81.                          form http:*). 
  82.        wwwmailcap.pl  -- a package of library utilities for handling MIME
  83.                          mailcap files and executing viewers by content-type.
  84.        wwwmime.pl     -- a package of library utilities for handling MIME
  85.                          content-types and message headers. 
  86.        wwwurl.pl      -- a package of library utilities for parsing, composing,
  87.                          manipulating, and canonicalizing Uniform Resource
  88.                          Locators (URLs) as they are used by the World-Wide Web
  89.                          software and protocols. 
  90.  
  91.  
  92. 3. Edit the Makefile to match your system configuration.  All you should
  93.    need to change is the value of PERLBIN -- the full pathname of your
  94.    perl interpreter.  Then, perform the command
  95.  
  96.       % make
  97.  
  98.    If the full pathname of your perl interpreter is not "/usr/public/bin/perl",
  99.    you should also perform the command:
  100.  
  101.       % make config
  102.    
  103.  
  104. 4. Set the LIBWWW_PERL environment variable to point to the
  105.    libwww-perl directory, e.g. 
  106.  
  107.         % setenv LIBWWW_PERL /usr/local/lib/libwww-perl-V.vv
  108.  
  109.    This allows clients like "get" to place the libwww-perl on their @INC path
  110.    and also allows wwwmime.pl to find the standard mime.types file.
  111.  
  112.  
  113. 5. That's it.  You should now be able to run get, HEAD and POST, as well
  114.    as the other library test* programs.  See the usage info and the
  115.    FAQ list below for more information.
  116.  
  117.  
  118. ==========================================================================
  119. Usage:
  120.  
  121. See the "get" and test* programs for examples of how to interface with
  122. libwww-perl.  More documentation will be available later.
  123.  
  124. The "get" program is a production-quality WWW client, useful for performing
  125. quick downloads from HTTP servers, translating FILE directories to HTML,
  126. and testing request/response headers on HTTP servers.
  127.  
  128. usage: get [-heqd] [-b BaseURL] [-t Timeout] [-i IMS_date] [-c ContentType]
  129.            [URL ...]
  130.  
  131. GET/0.5 -- A program for sending GET requests for World-Wide Web URLs
  132. Options:                                                        [DEFAULT]
  133.      -h  Help    -- just display this message and quit.
  134.      -e  Display the request and response headers to STDERR.    [STDOUT]
  135.      -q  Don't display the request and response headers.
  136.      -d  Don't display the content (useful for debugging servers).
  137.      -b  Start with the given Base URL.
  138.          [file://localhost/co/ub/fielding/public/www/lwp/libwww-perl/]
  139.      -t  Start with the given Timeout value (in seconds)        [30]
  140.      -i  Add the If-Modified-Since header (an HTTP date) to GET requests.
  141.      -c  Use the given MIME Content-type for POST, PUT, and CHECKIN requests.
  142.          [application/x-www-form-urlencoded]
  143. URL ...  Perform the GET request on each URL listed.
  144.  
  145. If no URLs are listed on the command-line, the program enters an
  146. interactive mode.  The following commands are available interactively:
  147.  
  148.      base=BaseURL    -- changes the current Base URL to that given.
  149.      tout=NNNN       -- sets the current Timeout value (in seconds).
  150.      ims=IMS_date    -- sets the If-Modified-Since header value.
  151.      URL             -- performs the request on the given URL.
  152.  
  153.  
  154. Here's a nice way to download information AND see the response headers:
  155.  
  156.      % get -e http://www.ics.uci.edu/WWWdocs/papers/rfc1630.txt > rfc1630.txt
  157.  
  158. And, since the method used is equal to the program's name (uppercased),
  159. you can use symbolic links to create other useful programs, e.g.
  160.  
  161.      % echo "tick=sunw" | POST http://www.secapl.com/cgi-bin/qs
  162.  
  163. Give it a try.  I have only tested the GET, HEAD, and POST methods, but all the
  164. others are supported as well (though they may not be supported by any server).
  165.  
  166. ==========================================================================
  167. Frequently Asked Questions
  168.  
  169. 1. Why doesn't libwww-perl support FTP, Gopher, WAIS, ... ?
  170.  
  171.    Because you haven't written the interface yet ;-)
  172.  
  173.    Seriously, though, all you need to do to add a new protocol to the
  174.    library is to copy an existing one (e.g. "cp wwwhttp.pl wwwftp.pl")
  175.    and define the contents of the %AllowedMethods array and the scheme's
  176.    request function (e.g. wwwftp'request()), and then include a "require"
  177.    statement in the main program that uses it.  That's it -- determination
  178.    of whether or not a protocol module exists is made dynamically by
  179.    &www'request().
  180.  
  181.  
  182. 2. How do I contribute my changes to the standard distribution?
  183.  
  184.    First, you should join the mailing list <libwww-perl@ics.uci.edu>
  185.    by sending a subscribe request, including your name and preferred e-mail
  186.    address, to <libwww-perl-request@ics.uci.edu>.  You will be sent a welcome
  187.    message when you are placed on the list.  To see what the list looks like,
  188.    see the Hypermail Archive of it at:
  189.  
  190.        <http://www.ics.uci.edu/WebSoft/libwww-perl/archive/>
  191.  
  192.    After that, send a mail message describing your changes or suggestions 
  193.    to <libwww-perl@ics.uci.edu> and we can all talk about them.
  194.    If you have RCS (or CVS), you can use the included RCS repository
  195.    to keep track of your changes and merge them with later distributions.
  196.    You are also free to send changes to others by mail or news (or even disk),
  197.    just as long as you don't claim they are part of the "standard distribution"
  198.    of libwww-perl.
  199.  
  200.  
  201. 3. Help, I have encountered a bug and I don't know what to do...
  202.  
  203.    First, look at the hypertext archive (the URL above) to see if a similar
  204.    problem has already been discussed on the mailing list.  If not, send a
  205.    message to the mailing list <libwww-perl@ics.uci.edu> which describes the
  206.    problem and symptoms, etc.  Above all, be sure to mention what platform
  207.    you are running on, since most of the problems discovered so far have
  208.    been platform-specific.  Finally, if you solve a problem, be sure to send
  209.    the solution to the mailing list as well.
  210.  
  211.  
  212. 4. Undefined subroutine "main'_BSD" called at /usr/local/lib/perl/sys/socket.ph
  213.  
  214.    Arrgh!
  215.  
  216.    This has been the big problem so far with SVR4 and mach-based system
  217.    installs.  What you need to do is create a sys/socket.ph file for your
  218.    perl standard library which is valid for your system.  Normally,
  219.    you can just run the "h2ph" command (part of the perl distribution) to set
  220.    up the files, but some SVR4 and mach-based systems use extra symbols which
  221.    can't be found by h2ph.  So, you need to do one (or more) of the following:
  222.  
  223.    A. Comment out the lines in sys/socket.ph that generate errors (they are
  224.       rarely needed in any case).
  225.  
  226.    B. Add your own definitions to the sys/socket.ph, e.g.
  227.  
  228.            eval 'sub BSD { 0; }';
  229.  
  230.       You may have to guess the correct value, or do a grep on
  231.       /usr/include/sys/*.h  to find the exact definition.
  232.  
  233.    C. Create your own canned socket.ph file via the included C program
  234.       sys_socket_ph.c -- compile and run it using the commands:
  235.  
  236.         % make socket
  237.         % sys_socket_ph > my_socket.ph
  238.  
  239.       and then edit "wwwhttp.pl" (in the libwww-perl stuff) to replace
  240.       the require "sys/socket.ph" with require "my_socket.ph";
  241.  
  242.    Depending on the vagaries of your system, at least one of the above
  243.    fixes should work.
  244.  
  245. ==========================================================================
  246. Have fun,
  247.  
  248. ......Roy Fielding   ICS Grad Student, University of California, Irvine  USA
  249.                     <fielding@ics.uci.edu>  <libwww-perl-request@ics.uci.edu>
  250.                      <URL:http://www.ics.uci.edu/dir/grad/Software/fielding>
  251.